I really like this PR. It clarifies a lot of aspects around the block storage logic and introduces a clear single entry point for it. Great work on that part!

That said, I have some concerns about moving more business logic into the database layer.

I had the same thought while writing this PR. I hink its better to make the DB operations independent of chainstate logic, but was having a hard time enforcing the privacy restrictions i wanted as a result/I wanted to quickly prove that accept_block was truly the only point of insertion into the db. I do think its worth revisiting/additional effort to enforce better separation while keeping tighter restrictions on the db access. Let me see what I can do today cause I prob didn't give it enough thought.

That said, I have some concerns about moving more business logic into the database layer.

Can you elaborate more on this point? What business logic features do you believe are present in the database layer that could be moved out?

That said, I have some concerns about moving more business logic into the database layer.

Can you elaborate more on this point? What business logic features do you believe are present in the database layer that could be moved out?

I was thinking specifically store_block_if_better (which mostly calls already existing db functions though). However it does have logic around orphaned blocks, signing weight, etc. that seem a bit like they shouldn't be in the db transaction? But not sure how else to set this up. I would expect the outer caller to do these sorts of checks but then it means exposing all those inner db calls...so this is why I ended up where I ended up

I was thinking specifically store_block_if_better (which mostly calls already existing db functions though). However it does have logic around orphaned blocks, signing weight, etc. that seem a bit like they shouldn't be in the db transaction? But not sure how else to set this up. I would expect the outer caller to do these sorts of checks but then it means exposing all those inner db calls...so this is why I ended up where I ended up

Right -- store_block_if_better is part of the transaction logic precisely because it has to happen within a database transaction. It's performing reads and writes on multiple records which must happen atomically with respect to other reads and writes. This atomicity requirement is what drives the current factoring. Otherwise, as you pointed out, we'd end up polluting the business logic with a lot of nitty-gritty details of transaction management, which I think is a worse outcome than the status quo since it creates more opportunities for accidental consensus bugs. To speak to @fdefelici's point, I think of this function as one of many different "update" methods exposed by the DB.

Right -- store_block_if_better is part of the transaction logic precisely because it has to happen within a database transaction. It's performing reads and writes on multiple records which must happen atomically with respect to other reads and writes. This atomicity requirement is what drives the current factoring. Otherwise, as you pointed out, we'd end up polluting the business logic with a lot of nitty-gritty details of transaction management, which I think is a worse outcome than the status quo since it creates more opportunities for accidental consensus bugs. To speak to @fdefelici's point, I think of this function as one of many different "update" methods exposed by the DB.

I think the current factoring was primarily driven by the goal of centralizing this piece of business logic, which is definitely a good direction.
That said, I don’t see any transaction management details here (just a series of CRUD operations on the DB). The actual transaction handling (creation, commit, rollback) still happens outside (for instance, in NakamotoChainState).

My main concern is simply where we choose to place this centralized logic.

In my view, deciding whether one block is “better” than another shouldn’t be the DB’s responsibility, because that logic could evolve in future epochs. This effectively gives the DB two distinct “reasons to change” (one business-related, one data-related) which can blur its purpose.

As @jferrant mentioned, it might be that for now the only practical place to host this logic (due to code constraints) is within the transaction layer. I assume because of the dependency with NakamotoStagingBlocksTx::add_shadow_block operation.

More broadly, beyond this specific function, what concerns me most is that it’s not fully clear (at least to me) where this kind of logic is expected to live going forward. For example:

• NakamotoChainState and StacksChainstate both contain business logic around DB/TXS operations.
• NakamotoStagingBlocksTx also embeds some business logic on top of the staging DB.
• NakamotoStagingBlocksConnRef focuses more purely on DB logic.
• Some DB operations that feel “natural” to expose at the DB layer have been made private.
• These changes are already having an effect on test organization (as described in my earlier comment).

To illustrate what I mean about boundary clarity:

• In NakamotoChainState::accept_block, there’s logic that manipulates the staging DB directly. Following the same principle as in this PR (or the one you shared above), that logic could arguably move into NakamotoStagingBlocksTx instead.
• Comparing NakamotoStagingBlocksTx and NakamotoStagingBlocksConnRef, it’s not immediately clear where DB logic (read query) belong. Trying to extract a "rule of thumb" it seems that NakamotoStagingBlocksTx should be used for write operations, and NakamotoStagingBlocksConnRef for read operations, but for instance, yet we have cases like NakamotoStagingBlocksTx::has_nakamoto_block_with_block_hash (a read operation).

Overall, these boundaries feel a bit opaque, which can make the code harder to reason about and maintain, at least from my current understanding of the system.

That said, this PR is still a solid improvement and a positive step forward.
As mentioned in my initial comment, this discussion wasn’t meant to block it, so I’ll go ahead and approve.

Happy to continue this conversation if others have additional thoughts.

Codecov Report

❌ Patch coverage is 87.96296% with 13 lines in your changes missing coverage. Please review.
✅ Project coverage is 77.09%. Comparing base (c5cca10) to head (61c819a).
⚠️ Report is 8 commits behind head on develop.

❌ Your project status has failed because the head coverage (77.09%) is below the target coverage (80.00%). You can increase the head coverage or adjust the target coverage.

@@             Coverage Diff             @@
##           develop    #6585      +/-   ##
===========================================
+ Coverage    76.19%   77.09%   +0.89%     
===========================================
  Files          571      571              
  Lines       351593   351577      -16     
===========================================
+ Hits        267882   271032    +3150     
+ Misses       83711    80545    -3166     

This pull request has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.